chore(release): 3.1.0 — align version surfaces, document undocumented commits - #130

…rsions ship silently

The hypermnesia-mcp-viz marketplace pin read version "3.0.0" for six days
with no matching cortex-viz tag (v2.8.0 was, and remained, the latest real
one). check_marketplace_pins.py never caught it: PIN_BEHIND_RELEASE only
ever asked "is the pin behind the latest known tag?" — a pin sitting AHEAD
of every real release read as current and passed silently.

Root cause, fixed at the source: add PIN_VERSION_UNPUBLISHED (existence,
not staleness) for both github-source and self-source pins, and the same
principle for a third version surface this incident exposed — the public
MCP registry (io.github.cdeust/hypermnesia-mcp was published at 4.17.1
while the tag/server.json/PyPI were already at 4.17.2, invisible until
queried directly): REGISTRY_VERSION_STALE, exact-equality against
server.json's own declared version.

- scripts/check_marketplace_pins.py split into a thin composition-root
  facade + 5 single-purpose modules (marketplace_pins_{http,semver,github,
  self,manifests,registry}.py) — the single file crossed the 300-line
  §4.1 cap once REGISTRY_VERSION_STALE was added. AP's byte-identical
  mirror needs the same split; its weekly diff job will show that until
  synced, which is the intended signal, not a regression.
- PENDING_PINS / PENDING_REGISTRY: a real, correctly-flagged finding whose
  fix is genuinely in flight (a real open PR, or a workflow that only
  fires on the next tag) degrades to a named, non-silent NOTICE instead
  of a red run — never a placeholder, always naming the tracking
  reference, dead code once the real state catches up.
- Corrected an unverified hypothesis relayed from another session: the
  marketplace schema does NOT accept only a raw sha. Checked against
  https://json.schemastore.org/claude-code-marketplace.json (2026-08-10):
  a github-source pin's `ref` field ("Git branch or tag to use") is
  schema-legal. The hypermnesia-mcp-viz pin now carries `ref: "v3.1.0"`
  alongside `sha` (kept for immutability — a tag ref alone can be
  force-moved after the fact; PIN_SHA_UNREACHABLE verifies it
  independently) so the pin self-documents its target.
- Bumped the pin to the real cortex-viz v3.1.0 release
  (052e4a40d3e6bddaeb1cec6662e23b451575c481, cdeust/cortex-viz#130):
  merged, tagged, PyPI-published (verified live on pypi.org 2026-08-10).
  Supersedes Cortex#418, whose sha (064e6d1) was a provisional PR-head
  value that changed on squash-merge, per that PR's own note.
- Corrected three places in this repo that repeated the same "renamed in
  v3.0.0" claim cortex-viz's own CHANGELOG made (README.md,
  marketplace.json's cortex-viz shim description,
  plugins/cortex-viz-deprecated/hooks/hooks.json's live session-start
  notice, docs/codex-plugin.md) plus this repo's own CHANGELOG.md
  Unreleased entry (still in-progress prose, not settled history, so
  corrected in place rather than annotated). tests_py/scripts/
  test_codex_plugin_contract.py had hardcoded the dangling "3.0.0"/sha as
  its expected contract — fixed to the real v3.1.0/sha.
- Adds .github/workflows/release.yml::publish-mcp-registry: auto-publish
  server.json to registry.modelcontextprotocol.io on every v* tag via
  `mcp-publisher login github-oidc` (GitHub OIDC, no stored secret —
  checked against modelcontextprotocol/registry's own docs, not assumed
  to mirror PyPI Trusted Publishing). Checksum-pinned mcp-publisher v1.8.1
  binary. Uncovered and fixed a real blocker while wiring this:
  server.json's description was 113 chars against the registry's
  100-char schema limit (`mcp-publisher validate` 422) — shortened to 98.
  The actual registry publish of 4.17.2 is NOT done by this PR: it
  requires either the next v* tag (this job) or a maintainer with real
  mcp-publisher access — an interactive OAuth/PAT login attempt was
  correctly refused by this agent's own permission classifier, which is
  the right outcome for a sensitive, irreversible action taken by an
  autonomous agent.

Test: a dedicated regression replays the incident's exact historical
values (repo tags topping out at v2.8.0, pin "3.0.0") through both the
pre-fix and post-fix check_github_pin — silently (None, None) before,
PIN_VERSION_UNPUBLISHED after. 38 tests across 3 new + 1 modified test
file; full tests_py/scripts/ suite green (764 passed, 5 skipped).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…rsions ship silently (#419)

* fix(marketplace): close the pin-verification gap that let dangling versions ship silently

The hypermnesia-mcp-viz marketplace pin read version "3.0.0" for six days
with no matching cortex-viz tag (v2.8.0 was, and remained, the latest real
one). check_marketplace_pins.py never caught it: PIN_BEHIND_RELEASE only
ever asked "is the pin behind the latest known tag?" — a pin sitting AHEAD
of every real release read as current and passed silently.

Root cause, fixed at the source: add PIN_VERSION_UNPUBLISHED (existence,
not staleness) for both github-source and self-source pins, and the same
principle for a third version surface this incident exposed — the public
MCP registry (io.github.cdeust/hypermnesia-mcp was published at 4.17.1
while the tag/server.json/PyPI were already at 4.17.2, invisible until
queried directly): REGISTRY_VERSION_STALE, exact-equality against
server.json's own declared version.

- scripts/check_marketplace_pins.py split into a thin composition-root
  facade + 5 single-purpose modules (marketplace_pins_{http,semver,github,
  self,manifests,registry}.py) — the single file crossed the 300-line
  §4.1 cap once REGISTRY_VERSION_STALE was added. AP's byte-identical
  mirror needs the same split; its weekly diff job will show that until
  synced, which is the intended signal, not a regression.
- PENDING_PINS / PENDING_REGISTRY: a real, correctly-flagged finding whose
  fix is genuinely in flight (a real open PR, or a workflow that only
  fires on the next tag) degrades to a named, non-silent NOTICE instead
  of a red run — never a placeholder, always naming the tracking
  reference, dead code once the real state catches up.
- Corrected an unverified hypothesis relayed from another session: the
  marketplace schema does NOT accept only a raw sha. Checked against
  https://json.schemastore.org/claude-code-marketplace.json (2026-08-10):
  a github-source pin's `ref` field ("Git branch or tag to use") is
  schema-legal. The hypermnesia-mcp-viz pin now carries `ref: "v3.1.0"`
  alongside `sha` (kept for immutability — a tag ref alone can be
  force-moved after the fact; PIN_SHA_UNREACHABLE verifies it
  independently) so the pin self-documents its target.
- Bumped the pin to the real cortex-viz v3.1.0 release
  (052e4a40d3e6bddaeb1cec6662e23b451575c481, cdeust/cortex-viz#130):
  merged, tagged, PyPI-published (verified live on pypi.org 2026-08-10).
  Supersedes Cortex#418, whose sha (064e6d1) was a provisional PR-head
  value that changed on squash-merge, per that PR's own note.
- Corrected three places in this repo that repeated the same "renamed in
  v3.0.0" claim cortex-viz's own CHANGELOG made (README.md,
  marketplace.json's cortex-viz shim description,
  plugins/cortex-viz-deprecated/hooks/hooks.json's live session-start
  notice, docs/codex-plugin.md) plus this repo's own CHANGELOG.md
  Unreleased entry (still in-progress prose, not settled history, so
  corrected in place rather than annotated). tests_py/scripts/
  test_codex_plugin_contract.py had hardcoded the dangling "3.0.0"/sha as
  its expected contract — fixed to the real v3.1.0/sha.
- Adds .github/workflows/release.yml::publish-mcp-registry: auto-publish
  server.json to registry.modelcontextprotocol.io on every v* tag via
  `mcp-publisher login github-oidc` (GitHub OIDC, no stored secret —
  checked against modelcontextprotocol/registry's own docs, not assumed
  to mirror PyPI Trusted Publishing). Checksum-pinned mcp-publisher v1.8.1
  binary. Uncovered and fixed a real blocker while wiring this:
  server.json's description was 113 chars against the registry's
  100-char schema limit (`mcp-publisher validate` 422) — shortened to 98.
  The actual registry publish of 4.17.2 is NOT done by this PR: it
  requires either the next v* tag (this job) or a maintainer with real
  mcp-publisher access — an interactive OAuth/PAT login attempt was
  correctly refused by this agent's own permission classifier, which is
  the right outcome for a sensitive, irreversible action taken by an
  autonomous agent.

Test: a dedicated regression replays the incident's exact historical
values (repo tags topping out at v2.8.0, pin "3.0.0") through both the
pre-fix and post-fix check_github_pin — silently (None, None) before,
PIN_VERSION_UNPUBLISHED after. 38 tests across 3 new + 1 modified test
file; full tests_py/scripts/ suite green (764 passed, 5 skipped).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(marketplace): close dispatch silence, rebase, and make the replay real

Addresses REQUEST_CHANGES on #419.

1. BLOCK - _check_plugin_pin recognized only two of the marketplace
   schema's five source shapes (github, local-path) and silently
   returned ([], [], None) for the other three (npm, url, git-subdir),
   all schema-legal (verified live against
   https://json.schemastore.org/claude-code-marketplace.json), all
   currently unused by this repo's manifest (verified by reading every
   plugins[].source in it) but not by the dispatcher's own logic. That
   silence is exactly the defect class this gate exists to close, in
   code this same PR introduced. Fixed: a dict source with a recognized-
   but-unchecked type (npm/url/git-subdir) now fails loudly
   (UNVERIFIED_SOURCE_TYPE, naming the type and pointing at where to add
   a checker); any other shape (wrong type, unknown source key) fails
   loudly too (UNRECOGNIZED_SOURCE). 7 new tests in
   tests_py/scripts/test_check_marketplace_pins_dispatch.py replay the
   reviewer's exact npm/url probe plus git-subdir, an unknown dict, and
   two malformed non-dict/non-str shapes - every one now produces a
   failure, none pass silently.

2. BLOCK - rebased onto origin/main (e88e4e2). The branch was stale
   behind #414/#416/#417; check_craftsmanship.py --base origin/main (the
   exact invocation CI runs) is clean post-rebase.

3. Non-blocking, fixed anyway - the incident-replay tests now execute a
   frozen, verbatim copy of the pre-fix check_github_pin/check_self_pin
   logic (git blame: pre-e0661ad9) against the identical historical
   inputs, asserting it returns the old silent (None, None)/[] BEFORE
   asserting the current code returns the failure AFTER (frozen copies
   live in tests_py/scripts/_marketplace_pins_legacy_replay.py). The
   commit message on e0661ad asserted this replay already happened; it
   did not - only the new code was exercised, and the "before" was
   prose. This is what the prose should have described from the start.

Incidental fix required to keep this PR's own CI green: bumped
zetetic-team-subagents 2.36.0 -> 2.37.0 (a real v2.37.0 tag landed on
cdeust/zetetic-team-subagents at 2026-08-10T10:32Z, mid-session, from
unrelated work - confirmed via `gh release view`, not assumed). Unrelated
to items 1-3 and to this PR's actual subject; flagged here rather than
silently folded in.

Re-measured after, not before: check_craftsmanship.py --base origin/main
clean; check_marketplace_pins.py exits 0 live (one NOTICE, the already-
disclosed pending registry entry); ruff check/format clean; pyright 0
diagnostics on every touched file; tests_py/scripts/ 771 passed (up from
764 pre-review), 5 skipped.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(marketplace): sequence registry publish after PyPI; pin zetetic-team-subagents sha

Three more items from review on #419.

1. REFUSED, with evidence — the request was to replace "ai-architect-mcp-
   codebase" with "automatised-pipeline" in check_marketplace_pins.py's
   docstring (now marketplace_pins_manifests.py), citing an AP canonical-
   drift job failure. Direct verification (curl raw.githubusercontent.com/
   cdeust/Cortex/main/... + gh api against ai-architect-mcp-codebase's
   copy, both fetched and diffed this session) shows the OPPOSITE of the
   claim: Cortex main already reads "ai-architect-mcp-codebase" (the
   current name); AP's own copy still reads "automatised-pipeline" (the
   old one). Making the requested edit would reintroduce the exact half-
   rename the instruction itself warned against. AP's repo needs the fix,
   not Cortex's — out of scope for this PR. No change made here.

2. zetetic-team-subagents pin hardened the same way hypermnesia-mcp-viz
   already was: added `ref: "v2.37.0"` + `sha` (57a5723d..., verified via
   `gh api .../git/refs/tags/v2.37.0` and confirmed `identical` to `main`
   via the compare endpoint — not a dangling PR-head).

3. `publish-mcp-registry` re-sequenced: `needs: publish-pypi` (was
   `needs: build`, parallel to `publish-pypi` rather than after it). A
   registry entry naming a version before the PyPI package exists is the
   same PIN_VERSION_UNPUBLISHED-shaped defect this PR spends most of its
   diff closing, just pointed the other direction — nearly reintroduced
   it in the very job meant to fix the analogous drift. Verified against
   cortex-viz's own Release.yaml (`needs: [test, release]` on its
   publish-registry job, fetched and read this session), same rationale.

Re-measured after: check_craftsmanship.py --base origin/main clean;
check_marketplace_pins.py exits 0 live; actionlint clean on release.yml;
ruff check/format clean repo-wide; tests_py/scripts/ 771 passed, 5 skipped
(unchanged — no test asserts the two JSON/YAML-only edits' exact values,
appropriately, since neither introduces new logic).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>